CKYC Webhook
The following document highights the details of the CKYC Webhook:s
Objective
You have to create a webhook to receive CERSAI's success or error response.
Sample Payload
{
"status": 200,
"message": "CKYC Uploaded Successfully",
"application_status": "short_reject",
"transactionid": "transaction_id",
"appid": "",
"ckyc_no": "",
"errors": [
""
]
}
Payload Details
The following table provides the details of the parameters returned in the Webhook's Payload:
| Parameter | Type | Description |
|---|---|---|
status | integer | HTTP status code representing the result of the CKYC upload operation |
message | string | Descriptive message about the result of the CKYC upload |
application_status | string | Status of the CKYC application (e.g., short_reject, success, etc.) |
transactionid | string | The unique identifier for the transaction |
appid | string | The client-specific application ID |
ckyc_no | string | The CKYC number generated for the uploaded record (if available) |
errors | array of strings | List of error messages returned by CERSAI, if any |
Possible Values for application_status
The following table lists the possible values of application_status field returned in the CKYC Webhook's payload:
| Value | Description |
|---|---|
| short_reject | As soon as the documents are uploaded after Admin's approval, CERSAI rejects a few cases immediately (short response) because of basic errors. Those will be termed as "short_reject" |
| short_confirmed_match | As soon as the documents are uploaded after Admin's approval, CERSAI immediately (short response) flags a few cases which are already present in CERSAI database. Those will be termed as "short_confirmed" We will get CKYC number of the matched record |
| insufficient_balance | If Client's CERSAI wallet balance is not sufficient for upload |
| long_reject | Apart from short response, CERSAI will also provide long response after 1-2 days of upload. Cases rejected in long response are termed as "long_reject" |
| probable_match | In the long response, CERSAI will match all the data uploaded by the client in its own database and return the possible match where probability of matching is higher. We will get CKYC number of the matched records |
| long_confirmed_match | In the probable match cases where the probability is 100%, CERSAI will reject those cases stating confirmed match. We will get CKYC number of the matched record |
| success | Successfully uploaded. We will get CKYC number of the uploaded record |
| recon_upload_failure | Upload of the reconciliation batch failed due to an error |
| recon_no_match | Final reconciliation response from CERSAI indicating no match was found. You should reinitiate update for these cases |
| recon_confirmed_match | Final reconciliation response from CERSAI confirming a match |
| recon_error | An error occurred in the final reconciliation response |
Error Message Classifications for application_status
The errors array may contain error messages returned by CERSAI. The following tables below list all possible error messages, based on the value of application_status:
A. Short Validation Errors (short_reject)
These are caught instantly by CERSAI due to schema violations, formatting issues, or invalid codes.
| Error Message | Explanation | Error Handling |
|---|---|---|
| Please enter Applicant Father/Spouse Name Prefix | The CKYC form requires a prefix (e.g., Mr., Mrs.) for the father or spouse's name. This field is either empty or incorrectly filled | Add appropriate prefix (e.g., Mr., Mrs.) to the father/spouse name field |
| Please enter Valid PAN or Form60 | Either a valid PAN number or Form 60 must be provided. Both fields are missing or invalid | Provide a valid PAN number or submit Form 60 if PAN is not available |
| Proof Of Possession Of Aadhaar number length should be either 4 or 12 digits, This record could not be processed due to invalid data in 30 type | The Aadhaar number entered is neither four nor 12 digits, which is non-compliant with the expected format | Ensure Aadhaar number is entered in correct format; four (masked aadhaar, only the last four digits) or 12-digits |
| Please do not enter Image size more than 350 KB | Uploaded photo or document image exceeds the size limit of 350 KB, violating CKYC file upload constraints | Compress the image to be under 350 KB before uploading |
| Please enter a valid Permanent District code, PIN is not matching with District entered | The entered PIN code and district code do not match according to official postal data | Verify and correct the PIN code to match the selected district |
| Last 4 digits of Proof Of Possession Of Aadhaar number should be numeric, This record could not be processed due to invalid data in 30 type | The last four digits of Aadhaar must be numeric. Invalid characters (e.g., alphabets or symbols) were detected | Remove any non-numeric characters from the last four digits of Aadhaar |
| Either Father/Spouse name or Mother name details are mandatory. Please provide either of these values, Flag indicating Father or Spouse name is empty | At least one of the following must be filled: father/spouse or mother's name. The form has none | Provide either father/spouse name or mother's name |
| Please enter Applicant Father/Spouse Name Prefix, Please enter a valid Permanent District code, PIN is not matching with District entered | Multiple issues: (1) Prefix missing for Father/Spouse Name and (2) District–PIN mismatch | Address both the missing prefix and the district–PIN mismatch |
| Either Father/Spouse name or Mother name details are mandatory. Please provide either of these values, Flag indicating Father or Spouse name is empty, Permanent Address Line 1 should be entered, Please enter Permanent City/Town/Village | Four fields are missing or invalid: parent details, address line 1, and city/town/village | Fill all required fields: parent details, address line 1, and city/town/village |
| Please enter Permanent City/Town/Village | City/town/village field is empty or incorrectly entered in the address section | Fill in the city/town/village field in the address section |
| Please enter Valid Branch code | Branch code (likely of the financial institution) is missing or invalid | Provide the correct branch code of the financial institution |
| Please enter Valid Branch code, Either Father/Spouse name or Mother name details are mandatory. Please provide either of these values, Flag indicating Father or Spouse name is empty | Multiple errors: invalid branch code and missing parent/spouse details | Correct the branch code and provide parent/spouse details |
| Please enter a valid Permanent District code, PIN is not matching with District entered, Please do not enter Image size more than 350 KB | Three issues: district–PIN mismatch and oversized image upload | Correct the district–PIN mismatch and reduce image size |
| Please enter Applicant Father/Spouse Name Prefix, Please do not enter Image size more than 350 KB | Missing prefix for Father/Spouse Name and uploaded image exceeds size limit | Add prefix and compress the image to be under 350 KB |
| Permanent Address Line 1 should be entered, Please enter Permanent City/Town/Village | Both address line 1 and city/town/village are missing in the address section | Fill in both address line 1 and city/town/village |
| Permanent Address Line 1 should be entered, Permanent Address Line 3 should not exceed 55 characters | Address line 1 is missing and line 3 exceeds the maximum allowed length | Fill in address line 1 and shorten address line 3 to 55 characters or less |
| Please enter valid constitution type others value, Please enter a valid Registered office address/Place of business District code, PIN is not matching with District entered | "Others" was selected for constitution type but not specified, and the registered office address has a district–PIN mismatch | Specify the "Others" value and correct the district–PIN mismatch |
| Please enter Applicant Father/Spouse Name Prefix, Please enter Valid PAN or Form60 | Two mandatory fields are missing: name prefix and valid PAN/Form 60 | Provide both the name prefix and a valid PAN/Form 60 |
| Either Father/Spouse name or Mother name details are mandatory. Please provide either of these values, Flag indicating Father or Spouse name is empty, Permanent Address Line 1 should be entered | Missing parent details and permanent address line 1 | Provide parent details and fill in permanent address line 1 |
| Permanent Address Line 1 should be entered | Address line 1 is mandatory and has not been filled | Fill in the first line of the permanent address |
B. Long Validation Errors (long_reject)
These errors are detected during delayed backend validation performed by CERSAI, often based on character limits, field dependencies, or deeper business logic that goes beyond initial schema checks.
| Error Message | Explanation | Error Handling |
|---|---|---|
| FI Recon TAT lapsed | The Financial Institution (FI) did not complete reconciliation within the Turnaround Time (TAT) window, leading to automatic rejection. | Complete the reconciliation process within the specified TAT window |
| Rejected – ID provided already under process | The CKYC record with the given ID (likely PAN or Aadhaar) is already under processing. Duplicate submissions are not allowed. | Wait for the existing process to complete or use a different ID if applicable |
| Rejected by CKYCRR due to junk values detected in the record being uploaded | The record was rejected due to invalid or nonsensical (junk) data fields — possibly containing random characters, corrupted values, or missing mandatory formatting | Review and correct all data fields before resubmitting |
C. Short Confirmed Match (short_confirmed_match)
As soon as the documents are uploaded after Admin's approval, CERSAI immediately (short response) flags a few cases which are already present in CERSAI database. Those will be termed as "short_confirmed". We will get CKYC number of the matched record.
| Error Message | Explanation | Error Handling |
|---|---|---|
| PAN number already exists in the system with KYC number XXXXXXXXXX1234. Please download the record using CKYC REFERENCE ID | PAN already registered with CERSAI, leading to a direct match | Download the record using the provided CKYC REFERENCE ID |
| Last 4 digits of Aadhaar, Name, DOB and Gender match with that of CKYC no XXXXXXXXXX1234. Please download the record using CKYC REFERENCE ID. | Aadhaar and demographic details match an existing CKYC entry | Download the record using the provided CKYC REFERENCE ID |
| Please enter Valid PAN or Form60 | Missing or invalid PAN; Form 60 also not submitted | Provide a valid PAN or Form 60 and re-upload if required |
| PAN number already exists in the system with KYC number XXXXXXXXXX1234. Please download the record using CKYC REFERENCE ID.Permanent District code cannot be empty, Permanent State code is mandatory | Existing CKYC match found via PAN; additionally, mandatory fields like state/district are missing | Download the record using the provided CKYC REFERENCE ID and fill missing mandatory fields |
D. Long Confirmed Match (long_confirmed_match)
In the probable match cases where the probability is 100%, CERSAI will reject those cases stating confirmed match. We will get CKYC number of the matched record.
| Error Message | Explanation | Error Handling |
|---|---|---|
| NoSuchKey: The specified key does not exist. | CERSAI is unable to find the key in the internal system | Verify the key and ensure it exists in the system |
E. Probable Match (probable_match)
In the long response, CERSAI will match all the data uploaded by the client in its own database and return the possible match where probability of matching is higher. We will get CKYC number of the matched records
| Error Message | Explanation | Error Handling |
|---|---|---|
| Please enter valid Constitution Type | Constitution type field is blank or invalid | Select a valid constitution type from the provided options |
| Please enter valid document type submitted | Invalid or unsupported document type entered | Select a document type from the approved list of supported documents |
| Identity verification flag is mandatory | Missing identity Verification Flag in payload | Set the appropriate identity verification flag in the payload |
| Invalid Image Type | Uploaded image format not acceptable (e.g., unsupported extension) | Convert image to a supported format before uploading |
| Rejected - ID provided already under process | Duplicate submission — same ID already being processed by CERSAI | Wait for the existing process to complete before resubmitting |
| ReferenceError: person is not defined | Internal server-side error, likely in payload structure | Contact technical support for payload structure validation |
| FI Recon TAT lapsed | Financial Institution's TAT (turnaround time) exceeded | Complete reconciliation within the specified time window |